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anki_vector.util 


Utility functions and classes for the Vector SDK. 


Functions 


angle_z_to_quaternion (angle_z) 
block_while_none ([interval, max_iterations]) 
degrees (degrees) 

distance_inches (distance_inches) 
distance_mm (distance_mm) 

get_class_logger (module, obj) 
parse_command_args ([parser]) 

radians (radians) 

read_configuration (serial, name, logger) 


setup_basic_logging ([custom_handler, ...]) 


speed_mmps (Speed_mmps) 


Classes 


Angle ([radians, degrees]) 

BaseOverlay (line_thickness, line_color) 
Component (robot) 

Distance ([distance_mm, distance_inches]) 


ImageRect (x_top_left, y_top_left, width, height) 


This function converts an angle in the z axis 
Use this to denote a property that may neec 
An Angle instance set to the specified numk 
Returns an anki_vector.util.Distance instan 
Returns an anki_vector.util.Distance instan 
Helper to create logger for a given class (an 
Parses command line arguments. 

An Angle instance set to the specified numk 
Open the default conf file, and read it into a 
Helper to perform basic setup of the Pythor 


anki_vector.util.Speed instance set to the s| 


Represents an angle. 

A base overlay is used as a base cle 
Base class for all components. 
Represents a distance. 


Defines a bounding box within an i 


Matrix44 (mOO, m10, m20, m30, m01, m11, m271, ...) A 4x4 Matrix for representing the | 


Pose (x, y, Z[, qO, q1, q2, q3, angle_z, ...]) 
Position (x, y, Z) 
Quaternion ([qO, q1, q2, q3, angle_z]) 


RectangleOverlav (width. heightl. ...]) 


Represents where an object is in tr 
Represents the position of an obje: 
Represents the rotation of an obje 


A rectangle that can be drawn ont 


v Pan! , vu uw ae vy 


Speed ([Soeed_mmps]) Represents a speed. 
Vector2 (x, y) Represents a 2D Vector (type/unit: 


vector3 (x, y, Z) Represents a 3D Vector (type/unit: 


class anki_vector.util.Angle(radians=None, degrees=None) 
Represents an angle. 
Use the degrees() Of radians() Convenience methods to generate an Angle instance. 


Parameters 


¢ radians ( optional [ float |) - The number of radians the angle should represent 


(cannot be combined with degrees ) 


¢ degrees ( optional [ float |) - The number of degress the angle should represent 


(cannot be combined with radians ) 


abs_value 
The absolute value of the angle. 
If the Angle is positive then it returns a copy of this Angle, otherwise it returns -Angle. 


Type 


anki_vector.util.Angle 


degrees 


The angle in degrees. 


Return type 


float 


radians 


The angle in radians. 


Return type 


float 


class anki_vector.util.BaseOverlay(line_thickness, line_color) 


A base overlay is used as a base class for other forms of overlays that can be drawn on 
top of an image. 


Parameters 


¢ line_thickness ( int ) - The thickness of the line being drawn. 


¢ line_color ( tuple ) - The color of the line to be drawn. 


line_color 


The color of the line to be drawn. 


Return type 


tuple 


line_thickness 


The thickness of the line being drawn. 


Return type 


int 


class anki_vector.util.Component(robot) 
Base class for all components. 
grpc_interface 


A direct reference to the connected aiogrpc interface. 


class anki_vector .util.Distance(distance_mm=None, distance_inches=None) 


Represents a distance. 


The class allows distances to be returned in either millimeters or inches. 


Use the distance_inches() Of distance_mm() Convenience methods to generate a Distance 


instance. 


Parameters 


¢ distance_mm ( optional | float ]) - The number of millimeters the distance should 


represent (cannot be combined with distance inches ). 


e distance_inches ( optional [ float |) - The number of inches the distance should 


represent (cannot be combined with distance_mm ). 


distance_mm 


The distance in millimeters 


Return type 


float 


class anki_vector.util. ImageRect(x_top_left, y_top_left, width, height) 
Defines a bounding box within an image frame. 


This is used when objects and faces are observed to denote where in the robot’s camera 
view the object or face actually appears. It’s then used by the annotate module to show 
an outline of a box around the object or face. 


height 
The height of the object from when it was last visible within Vector’s camera view. 


Return type 


float 


scale_by(scale_multiplier) 
Scales the image rectangle by the multiplier provided. 


Return type 


None 


width 


The width of the object from when it was last visible within Vector’s camera view. 


Return type 


float 


x_top_left 


The top left x value of where the object was last visible within Vector’s camera view. 


Return type 


float 


y_top_left 


The top left y value of where the object was last visible within Vector’s camera view. 


Return type 


float 


class anki_vector .util.Matrix44(m00, m10, m20, m30, m01, m11, m21, m31, m02, m12, m22, 
m32, m03, m13, m23, m33) 


A 4x4 Matrix for representing the rotation and/or position of an object in the world. 


Can be generated from a quaternion for a pure rotation matrix, or combined with a 
position for a full translation matrix, as done by Pose.to_matrix() . 


forward_xyz 


The x,y,z components representing the matrix’s forward vector. 


Type 


tuple of 3 floats 


in_column_order 
The contents of the matrix in column order. 
Type 


tuple of 16 floats 


in_row_order 
The contents of the matrix in row order. 


Type 


tuple of 16 floats 


left_xyz 
The x,y,z components representing the matrix’s left vector. 


Type 


tuple of 3 floats 


pos_xyz 
The x,y,z components representing the matrix’s position vector. 


Type 


tuple of 3 floats 


set_forward(x, y, z) 


Set the x,y,z components representing the matrix’s forward vector. 
Parameters 
° X( float ) - The X component. 
¢ y( float ) - The Y component. 


¢ Z( float ) - The Z component. 


set_left(x, y, z) 
Set the x,y,z components representing the matrix’s left vector. 
Parameters 
° X( float ) - The X component. 
¢ y( float ) - The Y component. 


° Z( float ) - The Z component. 


set_pos(x, y, Z) 
Set the x,y,z components representing the matrix’s position vector. 
Parameters 
° X( float ) - The X component. 
¢ y( float ) - The Y component. 


¢ Z( float ) - The Z component. 


set_up(x, y, Z) 
Set the x,y,z components representing the matrix’s up vector. 
Parameters 
° X( float ) - The X component. 
¢ y( float ) - The Y component. 


¢ Z( float ) - The Z component. 


tabulated_string 


A multi-line string formatted with tabs to show the matrix contents. 


Return type 


str 


up_xyz 
The x,y,z components representing the matrix’s up vector. 
Type 


tuple of 3 floats 


class anki_vector .util.Pose(x, y, z, q0=None, q1=None, q2=None, q3=None, angle_z=None, 
origin_id=-1) 


Represents where an object is in the world. 


Whenever Vector is delocalized (i.e. whenever Vector no longer knows where he is - e.g. 
when he’s picked up), Vector creates a new pose starting at (0,0,0) with no rotation, with 
origin_id incremented to show that these poses cannot be compared with earlier ones. As 
Vector drives around, his pose (and the pose of other objects he observes - e.g. faces, his 
LightCube, charger, etc.) is relative to this initial position and orientation. 


The coordinate space is relative to Vector, where Vector’s origin is the point on the 
ground between Vector’s two front wheels. The X axis is Vector’s forward direction, the Y 
axis is to Vector’s left, and the Z axis is up. 


Only poses of the same origin_id can safely be compared or operated on. 


import anki_vector 
from anki_vector.util import degrees, Pose 


with anki_vector.Robot() as robot: 
pose = Pose(x=5@, y=0, z=0, angle _z=anki_vector.util.Angle(degrees=0) ) 
robot .behavior.go_to_pose(pose) 


define_pose_relative_this(new_pose) 


Creates a new pose such that new_pose’s origin is now at the location of this pose. 


Parameters 


new_pose (anki_vector.util.Pose) - The pose which origin is being changed. 


Returns 


A anki_vector.util.Pose Object for which the origin was this pose’s origin. 


is_comparable(other_pose) 
Checks whether these two poses are comparable. 
Poses are comparable if they’re valid and having matching origin IDs. 
Parameters 
other_pose - The other pose to compare against. Type is Pose. 
Returns 


True if the two poses are comparable, False otherwise. 


Return type 


bool 


is_valid 
True if this is a valid, usable pose. 


Return type 


bool 


origin_id 


An ID maintained by the robot which represents which coordinate frame this pose is 
in. 


Return type 


int 


position 
The position component of this pose. 
Return type 


Position 


rotation 


The rotation component of this pose. 


Return type 


Quaternion 


to_matrix() 


Convert the Pose to a Matrix44. 


Returns 


A matrix representing this Pose’s position and rotation. 


Return type 


Matrix44 


to_proto_pose_struct() 


Converts the Pose into the robot’s messaging pose format. 


Return type 


PoseStruct 


class anki_vector.util.Position(x, y, z) 
Represents the position of an object in the world. 


A position consists of its x, y and z values in millimeters. 


Parameters 


¢ X( float ) - X position in millimeters 
¢ y( float ) - Y position in millimeters 


¢ Z( float ) - Z position in millimeters 


class anki_vector .util.Quaternion(q0=None, q1=None, q2=None, q3=None, angle_z=None) 


Represents the rotation of an object in the world. 
angle z 
An Angle instance representing the z Euler component of the object's rotation. 
Defined as the rotation in the z axis. 


Return type 


Angle 


qe 
The gO (w) value of the quaternion. 


Return type 


float 


q@_qi_q2_q3 
Contains all elements of the quaternion (q0,q1,q2,q3) 
Type 


tuple of float 


qi 
The qi (i) value of the quaternion. 
Return type 


float 


q2 
The q2 (j) value of the quaternion. 
Return type 


float 


q3 


The q3 (k) value of the quaternion. 


Return type 


float 


to_matrix(pos_x=0.0, pos_y=0.0, pos_z=0.0) 
Convert the Quaternion to a 4x4 matrix representing this rotation. 
A position can also be provided to generate a full translation matrix. 
Parameters 
* pos_x( float ) - The x component for the position. 
¢ pos_y( float ) - The y component for the position. 
¢ pos_Z( float ) - The z component for the position. 
Returns 


A matrix representing this Quaternion’s rotation, with the provided position (which 
defaults to 0,0,0). 


Return type 


anki_vector.util.Matrix44 
class anki_vector .util.RectangleOverlay(width, height, line_thickness=5, line_color=(255, 0, O)) 


A rectangle that can be drawn on top of a given image. 


Parameters 


¢ width ( int ) - The width of the rectangle to be drawn. 
¢ height ( int ) - The height of the rectangle to be drawn. 
¢ line_thickness ( int ) - The thickness of the line being drawn. 


¢ line_color ( tuple ) - The color of the line to be drawn. 


apply_overlay(image) 
Draw a rectangle on top of the given image. 


Return type 


None 


height 
The height of the rectangle to be drawn. 


Return type 


int 


width 
The width of the rectangle to be drawn. 
Return type 


int 


class anki_vector.util.Speed(speed_mmps=None) 
Represents a speed. 
This class allows speeds to be measured in millimeters per second. 
The maximum speed is 220 mm/s and is clamped internally. 
Use speed_mmps() Convenience methods to generate a Speed instance. 
Parameters 


speed_mmps ( optional [ float |) - The number of millimeters per second the speed 


should represent. 


speed_mmps 
The speed in millimeters per second (mmps). 
Return type 


float 


class anki_vector.util.Vector2(x, y) 
Represents a 2D Vector (type/units aren't specified). 
Parameters 
° X( float ) - X component 


¢ y( float ) - Y component 


set_to(rhs) 


Copy the x and y components of the given Vector2 instance. 


Parameters 


rhs - The right-hand-side of this assignment - the source Vector2 to copy into this 


Vector2 instance. 


The x component. 


Return type 


float 


Xx_y 
The X, Y elements of the Vector2 (x,y) 


Type 


tuple (float, float) 


The y component. 


Return type 


float 


class anki_vector.util.Vector3(x, y, z) 


Represents a 3D Vector (type/units aren't specified). 


Parameters 


¢ X( float ) - X component 
¢ y( float ) - Y component 


¢ Z( float ) - Z component 


cross(other) 


The cross product of this and another Vector3 instance 


dot(other) 


The dot product of this and another Vector3 instance 


magnitude 


The magnitude of the Vector3 instance 


Return type 


float 


magnitude_squared 


The magnitude of the Vector3 instance 


Return type 


float 


Type 


float 


normalized 


A Vector3 instance with the same direction and unit magnitude 


set_to(rhs) 


Copy the x, y and z components of the given Vectors instance. 


Parameters 


rhs - The right-hand-side of this assignment - the source Vector3 to copy into this 
Vector3 instance. 


The x component. 


Return type 


float 


X_y_Z 


The X, Y, Z elements of the Vector3 (x,y,z) 


Type 


tuple (float, float, float) 


The y component. 


Return type 


float 


The z component. 


Return type 


float 


anki_vector.util.angle_z_to_quaternion(angle_z) 


This function converts an angle in the z axis (Euler angle z component) to a quaternion. 


Parameters 
angle_z( angie ) - The z axis angle. 
Returns 
A tuple with all the members 


of a quaternion defined by angle_z. 


Return type 


qO, q1, q2, q3 (float, float, float, float) 





anki_vector.util.block_while_none(interval=0.1, max_iterations=50) 
Use this to denote a property that may need some delay before it appears. 
Parameters 
¢ interval ( float ) - how often to check if the property is no longer None 
* max_iterations ( int ) - how many times to check the property before raising an 


error 


This will raise a VectorcontrolTimeoutException if the property cannot be retrieved before 


max_iterations . 


anki_vector.util.degrees(degrees) 


An Angle instance set to the specified number of degrees. 


Return type 


Angle 


anki_vector.util.distance_mm(distance_mm) 


Returns an anki_vector.util.Distance instance set to the specified number of millimeters. 


anki_vector.util.distance_inches(distance_inches) 


Returns an anki_vector.util.Distance instance set to the specified number of inches. 





anki_vector.util.get_class_logger(module, obj) 


Helper to create logger for a given class (and module). 


import anki_vector 


logger = anki_vector.util.get_class_ logger("module_name", "“object_name") 


Parameters 


¢ module ( str ) - The name of the module to which the object belongs. 


¢ Obj ( object ) - the object that owns the logger. 


Return type 


Logger 





anki_vector.util.parse_command_args(parser=None) 
Parses command line arguments. 


Attempts to read the robot serial number from the command line arguments. If no serial 
number is specified, we next attempt to read the robot serial number from environment 
variable ANKI_LROBOT_SERIAL. If ANKILROBOT_SERIAL is specified, the value will be 
used as the robot’s serial number. 


import anki_vector 
import argparse 
parser = argparse.ArgumentParser() 


parser.add_argument("--new_param" ) 
args = anki_vector.util.parse_command_args(parser) 


Parameters 


parser ( optional [ ArgumentParser |) - To add new command line arguments, pass an 
argparse parser with the new options already defined. Leave empty to use the 


defaults. 


anki_vector.util.radians(radians) 


An Angle instance set to the specified number of radians. 


Return type 
Angle 
anki_vector.util.setup_basic_logging(custom_handler=None, general_log_level=None, 
target=None) 


Helper to perform basic setup of the Python logger. 


Parameters 


¢ custom_handler ( optional [ Handler |) - provide an external logger for custom 
logging locations 


¢ general_log level ( optional [ str |) - ‘DEBUG’, ‘INFO’, ‘WARN’, ‘ERROR’ or an 
equivalent constant from the logging module. If None then a value will be read 
from the VECTOR_LOG_LEVEL environment variable. 


¢ target ( object ) - The stream to send the log data to; defaults to stderr 


anki_vector.util.speed_mmps(speed_mmps) 


anki_vector.util.Speed instance set to the specified millimeters per second speed. 


